Skip to content

feat(app): hint at flag-style usage when commands are invoked positionally - #14

Merged
zoltanf merged 2 commits into
mainfrom
feat-usage-hint
Apr 30, 2026
Merged

zoltanf merged 2 commits into
mainfrom
feat-usage-hint

Conversation

@zoltanf

@zoltanf zoltanf commented Apr 30, 2026

Copy link
Copy Markdown
Owner

Summary

Closes the long-standing v1.0.7 polish item where Typer/Click's generic
Missing option '--name'. error left users with no path forward when
they ran something like:

rc0 record set example.com www A 1.2.3.4

instead of the flag form. The CLI now appends a one-line hint: after
Click's own message that lists the command's required flags:

Usage: rc0 record set [OPTIONS] ZONE
Try 'rc0 record set --help' for help.

Error: Missing option '--name'.
hint:  this command takes flags. Try: rc0 record set --name NAME --type TYPE

The fix is global — one handler in src/rc0/app.py covers every
command in the tree (record set/append/import, dnssec, tsig, …), no
per-command hooks. It fires for the three usage-error shapes a confused
positional-style user produces (Missing option, Missing argument,
Got unexpected extra argument) and stays silent for unrelated errors
like No such option.

Why

Item #6 from the v1.0.7 user-feedback triage
(~/.claude/plans/can-you-please-analyse-quirky-kahan.md) — a real
production user trying rc0 record add zone.com www A 1.2.3.4 got a
useless error and bounced. HANDOFF.md flagged this as the v1.0.8 polish
item, but v1.0.8 ended up shipping rc0 skill install instead and the
hint never landed. The record add/update/replace-all rename in
v2.0.0 didn't touch the underlying error class — same wart, same fix.

How

  • Switch the entry point to app(args=..., standalone_mode=False) so
    click.UsageError reaches our handler instead of Click's default
    exit-2 renderer.
  • New _format_usage_hint(exc) helper inspects exc.ctx.command.params
    for required click.Option instances and builds the hint string.
    Returns None (no hint) when there are no required options or the
    message doesn't match a positional-style trigger.
  • Existing Rc0Error / ConfirmationDeclined clauses are preserved
    ahead of the new generic ClickException clause, so the 4–12 exit
    codes don't regress.
  • _run is a small inner helper so tests can drive the entry point
    without subprocess.

Tests

  • Unit (tests/unit/test_usage_hint.py, 8 cases) — drives
    _format_usage_hint directly against synthetic UsageErrors for
    every branch (each trigger, no ctx, no required opts, unrelated
    message, Python-name type_ → TYPE placeholder mapping).
  • Integration (tests/integration/test_record_write_commands.py, 4
    new cases) — end-to-end via _run under capsys.

460 tests pass. Coverage 90.64% (up from the 88% gate).

Test plan

  • uv run ruff check . — clean
  • uv run ruff format --check . — clean
  • uv run mypy — clean
  • uv run pytest — 460 passed, 90.64% coverage
  • Manual: rc0 record set example.com www A 1.2.3.4 → hint fires
  • Manual: rc0 record set example.com → hint fires
  • Manual: rc0 record set example.com --bogus-flag → no hint (correct)
  • Manual: rc0 --version → exit 0 (no regression on the eager-callback path)
  • Manual: rc0 --token bogus zone show nonexistent.example.com → exit 4 with existing error: line (Rc0Error path intact)

zoltanf added 2 commits April 30, 2026 19:52
…onally

When a user types `rc0 record set zone.com www A 1.2.3.4` (positional)
instead of the flag form, Click exits 2 with a generic "Missing option
'--name'." with no path forward. This was a reported UX wart in the
v1.0.7 user-feedback triage (item #6) and was explicitly deferred to a
later release in HANDOFF.md, but never landed.

Switch the entry point to standalone_mode=False so we can intercept
click.UsageError and append a one-line `hint:` listing the command's
required flags. The hint fires for "Missing option", "Missing argument",
and "Got unexpected extra argument" — the three shapes a confused
positional-style user produces — and stays silent for unrelated errors
like "No such option". Same exit code (2), same Click message, just an
extra hint line.

Existing Rc0Error and ConfirmationDeclined paths still own their exit
codes (4–12); generic ClickException falls through to its own renderer.
Coverage rises to 90.64%.
… sanity test

Code-review pass on the usage-hint feature:

- Hoist `from rc0.app import _run` from inside each integration test
  to the file's top-level imports — matches the existing pattern (line 13).
- Drop `test_record_module_imported_for_resolution` — its assertions
  (record set/append are registered) are already exercised transitively
  by every other test in the file.
- Drop the test-narrating comment about Click's option-vs-positional
  ordering and the verbose docstrings — the assertions are
  self-documenting; per CLAUDE.md keep only non-obvious WHY.
- Replace the docstring on `test_hint_uses_canonical_flag_not_python_name`
  with the WHY (Typer's Python-name leakage) and add the same WHY to
  `test_run_returns_zero_on_version` (regression guard for the
  standalone_mode=False refactor).
@zoltanf
zoltanf merged commit 2e6a2fd into main Apr 30, 2026
5 checks passed
@zoltanf
zoltanf deleted the feat-usage-hint branch April 30, 2026 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant